home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / modelers / geomview / source.lha / Geomview / doc / geomview-2 < prev    next >
Text File  |  1993-12-06  |  51KB  |  1,489 lines
  1. Info file: geomview,    -*-Text-*-
  2. produced by texinfo-format-buffer
  3. from file: geomview.tex
  4.  
  5.  
  6. 
  7. File: geomview  Node: Cameras, Prev: Lighting Panel, Up: Interaction, Next: Saving
  8.  
  9. Cameras
  10. =======
  11.  
  12. A camera in Geomview is the object that corresponds to a camera window.
  13. By default there is only one camera, but it is possible to have as many
  14. as you want.  You can control certain aspects of the way the world is
  15. drawn in each camera window via the *Cameras* panel.
  16. If the target object is a camera, the *Cameras* panel affects that
  17. camera.  If the target object is not a camera, the *Cameras* panel
  18. affects the "current camera".  The current camera is the camera of
  19. the window that the mouse cursor is in, or was in most recently if the
  20. cursor is not in a camera window.  Thus, if you use the keyboard
  21. shortcuts for the actions in the *Cameras* panel while the cursor
  22. is in a camera window, the actions apply to that camera, unless you have
  23. explicitly selected another camera.
  24.  
  25.  
  26. *Add Camera*
  27.      Clicking on this button causes Geomview to create a new camera.  The
  28.      new camera's window appears, and an entry for it appears in the
  29.      *TARGET* browser of the *Main* panel.
  30.  
  31. *Software Shading*
  32.      This button controls whether Geomview does shading calculations in software.
  33.      The default is to let the hardware handle them, and in Euclidean space
  34.      this is almost certainly best because it is faster.  In hyperbolic and
  35.      spherical space, however, the shading calculations that the hardware
  36.      does are incorrect.  Click this button to turn on correct but slower
  37.      software shading.
  38.  
  39. *Background Color*
  40.      This button brings up a color chooser which you can use to set the
  41.      background color of the camera's window.
  42.  
  43. *PROJECTION*
  44.      This browser lets you pick between perspective and orthogonal projection
  45.      for this camera.
  46.  
  47. *Near clip*
  48.      This determines the distance in world coordinates of the near clipping
  49.      plane from the eye point.  It must be a positive number.
  50.  
  51. *Far clip*
  52.      This determines the distance in world coordinates of the far clipping
  53.      plane from the eye point.  It must be a positive number and in general
  54.      should be larger than the *Near clip* value.
  55.  
  56. *FOV*
  57.      This is the camera's field of view, measured in its shorter direction.
  58.      In perspective mode, it is an angle in degrees.  In orthographic mode,
  59.      it is the linear size of the field of view.  This number can be modified
  60.      with the mouse in *Cam Zoom* mode.
  61.  
  62. *Focal Length*
  63.      The focal length is intended to suggest the distance from the camera to
  64.      an imaginary plane of interest.  Its value is used when switching
  65.      between orthographic and perspective views (and during stereo viewing),
  66.      so as to preserve apparent size of objects lying at the focal distance
  67.      from the camera.
  68.  
  69. *Lines Closer*
  70.      This number has to do with the way lines are drawn.  Normally Geomview's
  71.      z-buffering algorithm can get confused when drawing lines that lie
  72.      exactly on surfaces (such as the edges of an object); due to machine
  73.      round-off error, sometimes the lines appear to be in front of the
  74.      surface and sometimes they appear behind it.  The *Lines Closer*
  75.      value is a fudge factor --- Geomview nudges all the lines that it draws
  76.      closer to the camera by this amount.  The number should be a small
  77.      integer; try 5 or 10.  0 turns this feature off completely.  Choosing
  78.      too large a value will make lines visible even though they should be
  79.      hidden.
  80.  
  81. *SPACE MODEL*
  82.      This determines the model used to draw the world.  It is most useful in
  83.      hyperbolic and spherical spaces.  You probably don't need to touch this
  84.      browser if you stay in Euclidean space.  For more information about
  85.      these models, *Note Non-Euclidean Geometry::.
  86.      *Virtual*
  87.           This is the default model and represents the natural view from inside
  88.           the space.
  89.  
  90.      *Projective*
  91.           The projective model of hyperbolic and spherical space.  Geoms move
  92.           under isometries of the space, and cameras move by Euclidean motions.
  93.           By default in the projective model, the Euclidean unit sphere is drawn.
  94.           In hyperbolic space this is the sphere at infinity.  In Euclidean space
  95.           the projective model is the same as the virtual model except that the
  96.           sphere is drawn by default.
  97.  
  98.      *Conformal*
  99.           The conformal model of hyperbolic and spherical space.  Geoms move under
  100.           isometries of the space, and cameras move by Euclidean motions.  In
  101.           Euclidean space, the conformal model amounts to inverting everything in
  102.           the unit sphere.
  103.  
  104. *Draw Sphere*
  105.      This controls whether Geomview draws the unit sphere.  By default the
  106.      unit sphere appears in the projective and conformal models.  In
  107.      hyperbolic space this is the sphere at infinity.  In spherical space it
  108.      is the equatorial sphere.
  109.  
  110. *Done*
  111.      This button dismisses the *Cameras* panel.
  112.  
  113.  
  114. 
  115. File: geomview  Node: Saving, Prev: Cameras, Up: Interaction, Next: Command Obscure
  116.  
  117. Saving your work
  118. ================
  119.  
  120. Geomview's *Save* panel lets you store Geomview objects and other
  121. information in files that you can read back into Geomview or other
  122. programs.
  123. To use the *Save* panel you select the desired format in the
  124. browser next to the word *Save*, enter the name of the object you
  125. want to save in the text field next to the word *for*, and enter
  126. the name of the file you wish to save to in the long text field next to
  127. the word *in*.  You can then either hit `RET' or click
  128. on the *OK* button.  When the file has been written, the *Save*
  129. panel disappears.  If you want to dismiss the *Save* panel without
  130. writing a file, click the *Cancel* button.
  131.  
  132. If you specify `-' as the file name, Geomview will write the file
  133. to standard output, i.e. in the shell window from which you invoked
  134. Geomview.
  135.  
  136. The possible formats are given below.  The kind of object that can
  137. be written with each format is given in parentheses.
  138.  
  139.  
  140. *Commands (any object)*
  141.      This write a file of gcl commands containing all information about
  142.      the object.  Loading this file later will restore the object as well as
  143.      all other information about it, such as appearance, transformations,
  144.      etc.
  145.  
  146. *Geometry alone (geom)*
  147.      This writes an OOGL file containing just the geometry of the object.
  148.  
  149. *Geometry [in world] (geom)*
  150.      This writes an OOGL file containing just the geometry of the object,
  151.      transformed under Geomview's current transformation for this object.
  152.      Use this if you have moved the object from its initial position and want
  153.      to save the new position relative to the world.
  154.  
  155. *Geometry [in universe] (geom)*
  156.      This writes an OOGL file containing just the geometry of the geom,
  157.      transformed under both the object's transformaton and the world's
  158.      transformation.
  159.  
  160. *RMan [->tiff] (camera)*
  161.      Writes a RenderMan file which when rendered creates a tiff image.
  162.  
  163. *RMan [->frame] (camera)*
  164.      Writes a RenderMan file which when rendered causes an image to appear in
  165.      an Iris window.
  166.  
  167. *SGI snapshot (camera)*
  168.      Write an SGI raster file.  A bell rings when the snapshot is complete.
  169.  
  170. *Camera (camera)*
  171.      Writes an OOGL file of a camera.
  172.  
  173. *Transform [to world] (any object)*
  174.      Writes an OOGL transform file giving Geomview's transform for the object.
  175.  
  176. *Transform [to universe] (any object)*
  177.      Writes an OOGL transform file giving a transform which is the
  178.      composition of Geomview's transform for the object and the transform for
  179.      the world.
  180.  
  181. *Window (camera)*
  182.      Writes an OOGL window file for a camera.
  183.  
  184. *Panels*
  185.      Writes a gcl file containing commands which record
  186.      the state of all the Geomview panels.  Loading this file later will
  187.      restore the positions of all the panels.
  188.  
  189.  
  190. 
  191. File: geomview  Node: Command Obscure, Prev: Saving, Up: Interaction, Next: Keyboard Shortcuts
  192.  
  193. The Commands and Obscure Panels
  194. ===============================
  195.  
  196. The *Commands* panel lets you type in a gcl command.  When
  197. you hit `RET', Geomview interprets the command and prints any
  198. resulting output or error messages on standard output.  You can edit the
  199. text and hit `RET' as many times as you like, in general,
  200. whenever you hit `RET' with the cursor in the *Commands*
  201. panel, Geomview tries to interpret whatever text you have typed in the
  202. text field as a command.
  203.  
  204. The *Obscure* panel is for relatively obscure things that don't
  205. really belong on any of the other panels.  In the present version of
  206. Geomview, the *Obscure* panel includes the *NORMALIZE GEOMETRY*
  207. browser, which controls the kind of geometry normalization that Geomview does,
  208. and several buttons affecting motion style.
  209.  
  210. Normalization is a kind of scaling; Geomview can scale an object so that
  211. it fits within a certain region.  The main point of normalization is to
  212. allow you to easily view all of an object without having to worry about
  213. how big it is.  We are gradually replacing Geomview's normalization
  214. feature with more robust camera positioning features.  In general, the
  215. best way to make sure you are seeing all of an object is to use the
  216. *Look At* button on the *Tools* panel.  Normalization may
  217. be completely replaced by this and other features in a future version of
  218. Geomview.
  219.  
  220. Normalization is a property that applies to each geom separately.  The
  221. *NORMALIZE GEOMETRY* browser affects the normalization property
  222. of target geom.  If the target geom is "World", it affects all geoms.
  223.  
  224.  
  225. *None*
  226.      Do no normalization.
  227.  
  228. *Individual*
  229.      Normalize this geom to fit within a unit sphere.
  230.  
  231. *Sequence*
  232.      This resembles "Individual", except when an object is changing.  Then,
  233.      "Individual" tightly fits the bounding box around the object whenever it
  234.      changes and normalizes accordingly, while "Sequence" normalizes the
  235.      union of all variants of the object and normalizes accordingly.
  236.  
  237. *Keep*
  238.      This leaves the current normalization transform unchanged when the
  239.      object changes.  It may be useful to apply "Individual" or "Sequence"
  240.      normalization to the first version of a changing object to bring
  241.      it in view, then switch to "Keep".
  242.  
  243.  
  244. The *Motion Style* controls include the following buttons.
  245.  
  246.  
  247. *[ui] Inertia*
  248.      Normally, moving objects have inertia: if the mouse is still moving
  249.      when the button is released, the selected object continues to move.
  250.      When *Inertia* is off, objects cease to move as soon as you release
  251.      the mouse.
  252.  
  253. *[uc] Constrain Motion*
  254.      It's sometimes handy to move an object in a direction aligned with a
  255.      coordinate axis: exactly horizontally or vertically.  Selecting
  256.      *Constrain Motion* changes the interpretation of mouse motions
  257.      to allow this; approximately-horizontal or approximately-vertical mouse dragging
  258.      becomes exactly horizontal or vertical motion.  Note that the motion is
  259.      still along the X or Y axes of the camera in which you move the mouse,
  260.      not necessarily the object's own coordinate system.
  261.  
  262. *[uo] Own Coordinates*
  263.      It's sometimes handy to move objects with respect to the coordinate system
  264.      where they were defined, rather than with respect to some camera.  While
  265.      *Own Coordinates* is selected, all motions are interpreted that way:
  266.      dragging the mouse rightward in translate mode moves the object in its own +X
  267.      direction, and so on.  May be especially useful in conjunction with
  268.      the *Constrain Motion* button.
  269.  
  270.  
  271.  
  272. 
  273. File: geomview  Node: Keyboard Shortcuts, Prev: Command Obscure, Up: Interaction, Next: OOGL File Formats
  274.  
  275. Keyboard Shortcuts
  276. ==================
  277.  
  278. Most actions that you can do through Geomview's panels have equivalent
  279. keyboard shortcuts so that you can do the same action by typing a
  280. sequence of keys on the keyboard.  This is useful for advanced users who
  281. are familiar with Geomview's capabilities and want to work quickly
  282. without having to have lots of panels cluttering up the screen.
  283. Keyboard shortcuts usually are indicated in square brackets ([ ]) near
  284. the corresponding item in a panel.  For example, the keyboard shortcut
  285. for *Rotate* mode is 'r'; this is indicated by "[r]" appearing
  286. before the word "Rotate" in the *MOTION MODE* browser.  To
  287. use this keyboard shortcut just hit the `r' key while the mouse
  288. cursor is in any Geomview window.  Do not hit the `RET' key
  289. afterwards.
  290.  
  291. Some keyboard shortcuts consist of more than one key.  In these cases
  292. just type the keys one after the other, with no `RET'
  293. afterwards.  Keyboard shortcuts are case sensitive.  You can cancel a
  294. multi-key keyboard shortcut that you have started by typing any invalid
  295. key, for example `^'.
  296.  
  297. Keyboard commands apply while the cursor is in any camera window and
  298. most control panels.
  299.  
  300. Many keyboard shortcuts allow numeric arguments which you type as a
  301. prefix to the command key(s).  For example, the shortcut for
  302. *Near clip* in the camera panel is `v n'.  To set the near
  303. clip plane to "0.5", type `0.5 v n'.  Commands that don't take a
  304. numeric prefix toggle or reset the current value.
  305.  
  306. Most commands allow one of the following selection prefixes.  If none is
  307. provided the command applies to the target object.
  308.  
  309. `g'
  310.      world geom    
  311. `g#'
  312.      #'th geom
  313. `g*'
  314.      All geoms
  315. `c'
  316.      current camera
  317. `c#'
  318.      #'th camera
  319. `c*'
  320.      All cameras
  321.  
  322. For example, `g 4 a f' means toggle the face drawing of object
  323. *g4*.
  324.  
  325. The text field in the upper left corner of the *Main* panel
  326. shows the state of the current keyboard shortcut.
  327.  
  328. In addition to the keyboard shortcuts for the panel commands, there is
  329. also a shortcut for picking a target object: type the short name of the
  330. object followed by `p'.  For example, to select object *g3*,
  331. type `g 3 p'.  This only works with the short names --- the ones
  332. that appear in square brackets ([ ]) in the *TARGET* browser of
  333. the *Main* panel.
  334.  
  335. Below is a summary of all keyboard shortcuts.
  336.  
  337. Draw
  338.              `af'
  339.      
  340.               Faces
  341.               `ae'
  342.      
  343.               Edges
  344.               `an'
  345.      
  346.               Normals
  347.               `ab'
  348.      
  349.               Bounding Boxes
  350.               `aV'
  351.      
  352.               Vectors
  353.          Shading
  354.      
  355.              `0as'
  356.      
  357.               Constant
  358.               `1as'
  359.      
  360.               Flat
  361.               `2as'
  362.      
  363.               Smooth
  364.               `3as'
  365.      
  366.               Smooth, non-lighted
  367.               `aT'
  368.      
  369.               allow transparency
  370.          Other
  371.      
  372.              `av'
  373.      
  374.               eVert normals: always face viewer
  375.               `#aw'
  376.      
  377.               Line Width (pixels)
  378.               `#ac'
  379.      
  380.               edges Closer than faces (try 5-100)
  381.          Color
  382.      
  383.              `Cf'
  384.      
  385.               faces
  386.               `Ce'
  387.      
  388.               edges
  389.               `Cn'
  390.      
  391.               normals
  392.               `Cb'
  393.      
  394.               bounding boxes
  395.               `CB'
  396.      
  397.               background
  398.          Motions
  399.      
  400.              `r'
  401.      
  402.               rotate
  403.               `t'
  404.      
  405.               translate
  406.               `z'
  407.      
  408.               zoom FOV
  409.               `f'
  410.      
  411.               fly
  412.               `o'
  413.      
  414.               orbit
  415.               `s'
  416.      
  417.               scale
  418.               `w'
  419.      
  420.               recenter target
  421.               `W'
  422.      
  423.               recenter all
  424.               `h'
  425.      
  426.               halt
  427.               `H'
  428.      
  429.               halt all
  430.               `@'
  431.      
  432.               select center of motion (e.g. `g 3 @')
  433.               `L'
  434.      
  435.               Look At object
  436.          Viewing
  437.      
  438.              `0vp'
  439.      
  440.               Orthographic view
  441.               `1vp'
  442.      
  443.               Perspective view
  444.               `vd'
  445.      
  446.               Draw other views' cameras
  447.               `#vv'
  448.      
  449.               field of View
  450.               `#vn'
  451.      
  452.               near clip distance
  453.               `#vf'
  454.      
  455.               far clip distance
  456.               `v+'
  457.      
  458.               add new camera
  459.               `vx'
  460.      
  461.               cursor on/off
  462.               `vb'
  463.      
  464.               backfacing poly cull on/off
  465.               `#vl'
  466.      
  467.               focal length
  468.               `v~'
  469.      
  470.               Software shading on/off
  471.          Panels
  472.      
  473.              `Pm'
  474.      
  475.               Main
  476.               `Pa'
  477.      
  478.               Appearance
  479.               `Pl'
  480.      
  481.               Lighting
  482.               `Po'
  483.      
  484.               Obscure
  485.               `Pt'
  486.      
  487.               Tools
  488.               `Pc'
  489.      
  490.               Cameras
  491.               `PC'
  492.      
  493.               Commands
  494.               `Pf'
  495.      
  496.               Files
  497.               `Ps'
  498.      
  499.               Save
  500.               `P-'
  501.      
  502.               read commands from tty
  503.          Lights
  504.      
  505.              `ls'
  506.      
  507.               show lights
  508.               `le'
  509.      
  510.               edit lights
  511.          Space
  512.      
  513.              `me'
  514.      
  515.               Euclidean
  516.               `mh'
  517.      
  518.               Hyperbolic
  519.               `ms'
  520.      
  521.               Spherical
  522.          Model
  523.      
  524.              `mv'
  525.      
  526.               Virtual
  527.               `mp'
  528.      
  529.               Projective
  530.               `mc'
  531.      
  532.               Conformal
  533.          Other
  534.      
  535.              `0N'
  536.      
  537.               normalizaton: none
  538.               `1N'
  539.      
  540.               normalization: each
  541.               `2N all'
  542.      
  543.               normalization: all
  544.               `ui'
  545.      
  546.               motion: Inertia
  547.               `uc'
  548.      
  549.               motion: Constrain to axis
  550.               `uo'
  551.      
  552.               motion: object's Own coordinates
  553.               `<'
  554.      
  555.               `Pf'
  556.      
  557.               load geometry/command file
  558.               `dd'
  559.      
  560.               delete target object
  561.               `>'
  562.      
  563.               `Ps'
  564.      
  565.               save state to file
  566.               `TV'
  567.      
  568.               NTSC mode toggle
  569.               `p'
  570.      
  571.               pick as target object (e.g. `g 3 p')
  572.               With no prefix, selects the object under the
  573.               mouse cursor (like double-clicking the right mouse)
  574.     
  575. 
  576. File: geomview  Node: OOGL File Formats, Prev: Keyboard Shortcuts, Up: Top, Next: Conventions
  577.  
  578. OOGL File Formats
  579. *****************
  580.  
  581. The objects that you can load into Geomview are called OOGL objects.
  582. OOGL stands for "Object Oriented Graphics Library"; it is the library
  583. upon which Geomview is built.
  584.  
  585. There are many different kinds of OOGL objects.  This chapter gives
  586. syntactic descriptions of file formats for OOGL objects.
  587.  
  588. Examples of most file types live in Geomview's `data/geom'
  589. directory.
  590.  
  591. * Menu:
  592.  
  593. * Conventions::                   Conventions.
  594. * Object File Formats::           Object File Formats.
  595. * Non-geometric objects::         Non-geometric objects.
  596.  
  597. 
  598. File: geomview  Node: Conventions, Prev: OOGL File Formats, Up: OOGL File Formats, Next: Common syntax
  599.  
  600. Conventions
  601. ===========
  602.  
  603. * Menu:
  604.  
  605. * Common syntax::                  Syntax Common to All OOGL File Formats.
  606. * File names::                     File Names.
  607. * Vertices::                       Vertices.
  608. * Surface normal directions::      Surface normal directions.
  609. * Transformation matrices::        Transformation matrices.
  610. * Binary format::                  Binary format.
  611. * References::                     Embedded objects and external-object references.
  612. * Appearances::                    Appearances.
  613.  
  614. 
  615. File: geomview  Node: Common syntax, Prev: Conventions, Up: Conventions, Next: File names
  616.  
  617. Syntax Common to All OOGL File Formats
  618. --------------------------------------
  619.  
  620. Most OOGL object file formats are free-format ASCII --- any amount of
  621. white space (blanks, tabs, newlines) may appear between tokens (numbers,
  622. key words, etc.).  Line breaks are almost always insignificant, with a
  623. couple of exceptions as noted.  Comments begin with # and continue to
  624. the end of the line; they're allowed anywhere a newline is.
  625.  
  626. Binary formats are also defined for several objects; *Note Binary format::, and the individual object descriptions.
  627.  
  628. Typical OOGL objects begin with a key word designating object type,
  629. possibly with modifiers indicating presence of color information etc.
  630. In some formats the key word is optional, for compatibility with file
  631. formats defined elsewhere.  Object type is then determined by
  632. guessing from the file suffix (if any) or from the data itself.
  633.  
  634. Key words are case sensitive.  Some have optional prefix letters
  635. indicating presence of color or other data; in this case the order of
  636. prefixes is significant, e.g. `CNMESH' is meaningful but
  637. `NCMESH' is invalid.
  638.  
  639. 
  640. File: geomview  Node: File names, Prev: Common syntax, Up: Conventions, Next: Vertices
  641.  
  642. File Names
  643. ----------
  644.  
  645. When OOGL objects are read from disk files, the OOGL library uses the
  646. file suffix to guess at the file type.
  647.  
  648. If the suffix is unrecognized, or if no suffix is available (e.g. for an
  649. object being read from a pipe, or embedded in another OOGL object), all
  650. known types of objects are tried in turn until one accepts the data as
  651. valid.
  652.  
  653. 
  654. File: geomview  Node: Vertices, Prev: File names, Up: Conventions, Next: Surface normal directions
  655.  
  656. Vertices
  657. --------
  658.  
  659. Several objects share a common style of representing vertices with
  660. optional per-vertex surface-normal and color.  All vertices within an
  661. object have the same format, specified by the header key word.
  662.  
  663. All data for a vertex is grouped together (as opposed to e.g. giving
  664. coordinates for all vertices, then colors for all vertices, and so on).
  665.  
  666. The syntax is
  667.  
  668. `X  Y  Z'
  669.      (3-D floating-point vertex coordinates) or
  670. `X  Y  Z  W'
  671.      (4-D floating-point vertex coordinates)
  672.  
  673. optionally followed by
  674.  
  675. `NX  NY  NZ'
  676.      (normalized 3-D surface-normal if present)
  677.  
  678. optionally followed by
  679.  
  680. `R  G  B  A'
  681.      (4-component floating-point color if present, each component in range
  682.      0..1.  The A (alpha) component represents opacity: 0 transparent, 1
  683.      opaque.)
  684.  
  685. Values are separated by white space, and line breaks
  686. are immaterial.
  687.  
  688. 
  689. File: geomview  Node: Surface normal directions, Prev: Vertices, Up: Conventions, Next: Transformation matrices
  690.  
  691. Surface normal directions
  692. -------------------------
  693.  
  694. Geomview uses normal vectors to determine how an object is shaded.
  695. The direction of the normal is significant in this calculation.
  696.  
  697. When normals are supplied with an object, the direction of the normal
  698. is determined by the data given.
  699.  
  700. When normals are not supplied with the object, Geomview computes normal
  701. vectors automatically; in this case normals point toward the side from
  702. which the vertices appear in counterclockwise order.
  703.  
  704. On parametric surfaces (Bezier patches), the normal at point P(u,v)
  705. is in the direction dP/du cross dP/dv.
  706.  
  707. 
  708. File: geomview  Node: Transformation matrices, Prev: Surface normal directions, Up: Conventions, Next: Binary format
  709.  
  710. Transformation matrices
  711. -----------------------
  712.  
  713. Some objects incorporate 4x4 real matrices for homogeneous object
  714. transformations.  These matrices act by multiplication on the right of
  715. vectors.  Thus, if p is a 4-element row vector representing homogeneous
  716. coordinates of a point in the OOGL object, and A is the 4x4 matrix, then
  717. the transformed point is p' = p A.  This matrix convention is common in
  718. computer graphics; it's the transpose of that often used in mathematics,
  719. where points are column vectors multiplied on the right of matrices.
  720.  
  721.  
  722. Thus for Euclidean transformations, the translation components appear in
  723. the fourth row (last four elements) of A.  A's last column (4th, 8th,
  724. 12th and 16th elements) are typically 0, 0, 0, and 1 respectively.
  725.  
  726. 
  727. File: geomview  Node: Binary format, Prev: Transformation matrices, Up: Conventions, Next: References
  728.  
  729. Binary format
  730. -------------
  731.  
  732. Many OOGL objects accept binary as well as ASCII file formats.
  733. These files begin with the usual ASCII token (e.g. `CQUAD')
  734. followed by the word `BINARY'.
  735. Binary data begins at the byte following the first newline after
  736. `BINARY'.  White space and a single comment may intervene, e.g.
  737.  
  738.      OFF BINARY    # binary-format "OFF" data follows 
  739.  
  740. Binary data comprise 32-bit integers and 32-bit IEEE-format floats, both
  741. in big-endian format (i.e., with most significant byte first).  This is
  742. the native format for 'int's and 'float's on Sun-3's, Sun-4's, and
  743. Irises, among others.
  744.  
  745. Binary data formats resemble the corresponding ASCII formats, with ints
  746. and floats in just the places you'd expect.  There are some exceptions
  747. though, specifically in the `QUAD' and `OFF' file formats.
  748. Details are given in the individual file format descriptions.
  749. *Note QUAD::, and *Note OFF::.
  750.  
  751. Binary OOGL objects may be freely mixed in ASCII object streams:
  752.  
  753.      LIST
  754.      { = MESH BINARY
  755.      ... binary data for mesh here ...
  756.      }
  757.      { = QUAD
  758.          1 0 0   0 0 1   0 1 0  0 1 0
  759.      }
  760.  
  761. Note that ASCII data resumes immediately following the last byte of
  762. binary data.
  763.  
  764. Naturally, it's impossible to embed comments inside a binary-format OOGL
  765. object, though comments may appear in the header before the beginning of
  766. binary data.
  767.  
  768. 
  769. File: geomview  Node: References, Prev: Binary format, Up: Conventions, Next: Appearances
  770.  
  771. Embedded objects and external-object references
  772. -----------------------------------------------
  773.  
  774. Some object types (`LIST', `INST') allow references to other
  775. OOGL objects, which may appear literally in the data stream, be loaded
  776. from named disk files, or be communicated from elsewhere via named
  777. objects.  Gcl commands also accept geometry in these forms.
  778.  
  779. The general syntax is
  780.  
  781.       <oogl-object>  ::=
  782.          [ "{" ]
  783.              [ "define" `symbolname' ]
  784.              [ "appearance" `appearance' ]
  785.              [ ["="] `object-keyword' ...
  786.               | "<" `filename'
  787.               | ":" `symbolname' ]
  788.          [ "}" ]
  789.  
  790. where "quoted" items are literal strings (which appear without the
  791. quotes), [bracketed] items are optional, and | denotes alternatives.
  792. Curly braces, when present, must match; the outermost set of curly
  793. braces is generally required when the object is in a larger context,
  794. e.g. when it is part of a larger object or embedded in a Geomview
  795. command stream.
  796.  
  797. For example, each of the following three lines:
  798.          { define fred   QUAD 1 0 0  0 0 1  0 1 0  1 0 0 }
  799.  
  800.          { appearance { +edge } LIST { < "file1" } { : fred } }
  801.  
  802.          VECT 1 2 0   2 0   0 0 0   1 1 2
  803. is a valid OOGL object.  The last example is only valid when it is
  804. delimited unambiguously by residing in its own disk file.
  805.  
  806. The "<" construct causes a disk file to be read.  Note that this isn't a
  807. general textual "include" mechanism; a complete OOGL object must appear
  808. in the referenced file.
  809.  
  810. Files read using "<" are sought first in the directory of the file which
  811. referred to them, if any; failing that, the normal search path (set by
  812. Geomview's `load-path' command) is used.  The default search looks
  813. first in the current directory, then in the Geomview data directories.
  814.  
  815. The ":" construct allows references to symbols, created with
  816. `define'.  A symbol's initial value is a null object.  When a
  817. symbol is (re)defined, all references to it are automatically changed;
  818. this is a crucial part of the support for interprocess communication.
  819. Some future version of the documentation should explain this better...
  820.  
  821. Again, white space and line breaks are insignificant, and "#" comments
  822. may appear anywhere.
  823.  
  824.  
  825. 
  826. File: geomview  Node: Appearances, Prev: References, Up: Conventions, Next: Object File Formats
  827.  
  828. Appearances
  829. -----------
  830.  
  831. Geometric objects can have associated "appearance" information,
  832. specifying shading, lighting, color, wireframe vs. shaded-surface
  833. display, and so on.  Appearances are inherited through object
  834. hierarchies, e.g. attaching an appearance to a `LIST' means that the
  835. appearance is applied to all the `LIST''s members.
  836.  
  837. Some appearance-related properties are relegated to "material" and
  838. "lighting" substructures.  Take care to note which properties belong to
  839. which structure.
  840.  
  841. Here's an example appearance structure including values for all
  842. attributes.  Order of attributes is unimportant.  As usual, white space
  843. is irrelevant.  Boolean attributes may be preceded by "+" or "-" to turn
  844. them on or off; "+" is assumed if only the attribute name appears.
  845. Other attributes expect values.
  846.  
  847. A "*" prefix on any attribute, e.g. "*+edge" or "*linewidth 2",
  848. selects "override" status for that attribute.
  849.  
  850.      appearance {
  851.        +face               # draw faces of polygons
  852.        -edge               # don't draw edges of polygons
  853.        -transparent        # don't attempt transparency (not implemented)
  854.        +normal             # do draw surface-normal vectors
  855.        normscale .25       # ... with length .25 in object coordinates
  856.  
  857.        +evert              # do evert polygon normals where needed so as
  858.                            #   to always face the camera
  859.  
  860.        shading smooth      # or "shading constant" or "shading flat".
  861.                            # smooth = Gouraud shading; flat = faceted.
  862.  
  863.        linewidth 3         # lines & edges are 3 pixels wide.
  864.  
  865.        material {         # Here's a material definition;
  866.                            # it could also be read from a file as in
  867.                            #  "material < file.mat"
  868.  
  869.            ka  1.0         # ambient reflection coefficient.
  870.            ambient .3 .5 .3 # ambient color (red, green, blue components)
  871.                            # The ambient contribution to the shading is
  872.                            # the product of ka, the ambient color,
  873.                            # and the color of the ambient light.
  874.  
  875.            kd  0.8         # diffuse-reflection coefficient.
  876.            diffuse .9 1 .4 # diffuse color.
  877.                              # (In "shading constant" mode, the surface
  878.                              # is colored with the diffuse color.)
  879.  
  880.            ks 1.0          # specular reflection coefficient.
  881.            specular 1 1 1  # specular (highlight) color.
  882.            shininess  25   # specular exponent; larger values give
  883.                            # sharper highlights.
  884.  
  885.            alpha   1.0     # opacity; 0 = transparent (invisible)
  886.                            # when transparency is enabled.
  887.  
  888.            edgecolor   1 1 0  # line & edge color
  889.  
  890.            normalcolor 0 0 0  # color for surface-normal vectors
  891.        }
  892.  
  893.        lighting {         # Lighting model
  894.  
  895.            ambient  .3 .3 .3  # ambient light
  896.  
  897.            replacelights   # "Use only the following lights to
  898.                            # illuminate the objects under this
  899.                            # appearance."
  900.                            # Without "replacelights", any lights
  901.                            # are added to those already in the scene.
  902.  
  903.                            # Now a collection of real lights
  904.            light { 
  905.                color  1 .7 .6      # light color
  906.                position  1 0 .5 0  # light position [distant light]
  907.                                    # given in homogeneous coordinates.
  908.                                    # With fourth component = 0,
  909.                                    # this means a light coming from
  910.                                    # direction (1,0,.5).
  911.            }
  912.  
  913.            light {                        # Another light.
  914.                color 1 1 1
  915.                position  0 0 .5 1  # light at finite position ...
  916.                location camera     # specified in camera coordinates.
  917.                                    # (Since the camera looks toward -Z,
  918.                                    # this example places the light
  919.                                    # .5 unit behind the eye.)
  920.                # Possible "location" keywords:
  921.                #  global    light position is in world coordinates
  922.                #             This is the default if no location specified.
  923.                #  camera   position is in the camera's coordinate system
  924.                #  local    position is in the coordinate system where
  925.                #                   the appearance was defined
  926.            }
  927.        }                   # end lighting model
  928.      }                     # end appearance
  929.  
  930.  
  931. There are rules for inheritance of appearance attributes when several
  932. are imposed at different levels in the hierarchy.
  933.  
  934. For example, Geomview installs a backstop appearance which provides
  935. default values for most parameters; its control panels install other
  936. appearances which supply new values for a few attributes; user-supplied
  937. geometry may also contain appearances.
  938.  
  939. The general rule is that the child's appearance (the one closest to the
  940. geometric primitives) wins.  So setting an appearance attribute in an
  941. object's definition will prevent the viewer controls from affecting that
  942. object's display.
  943.  
  944. 
  945. File: geomview  Node: Object File Formats, Prev: Appearances, Up: OOGL File Formats, Next: QUAD
  946.  
  947. Object File Formats
  948. ===================
  949.  
  950. * Menu:
  951.  
  952. * QUAD::        List of quadrilaterals.
  953. * MESH::        Rectangularly-connected mesh.
  954. * BBP and BEZ::        List of Bezier surface patches.
  955. * OFF::            Polyhedra: polygons with shared vertices.
  956. * VECT::        List of points and lines.
  957. * INST::        Transformed Instance of another object.
  958. * LIST::        List of other objects.
  959. * TLIST::        Collection of 4x4 transformation matrices.
  960. * GROUP::        Obsolete format for collections of objects.
  961. * DISCGRP::             Discrete Group objects.
  962.  
  963.  
  964. 
  965. File: geomview  Node: QUAD, Prev: Object File Formats, Up: Object File Formats, Next: MESH
  966.  
  967. `QUAD': collection of quadrilaterals
  968. ------------------------------------
  969.  
  970. The conventional suffix for a `QUAD' file is `.quad'.
  971.  
  972. The file syntax is
  973.  
  974.         [C][N][4]QUAD  -or-  [C][N][4]POLY           # Key word
  975.         VERTEX  VERTEX  VERTEX  VERTEX  # 4*N vertices for some N
  976.         VERTEX  VERTEX  VERTEX  VERTEX
  977.         ...
  978.  
  979. The leading key word is `[C][N][4]QUAD' or `[C][N][4]POLY',
  980. where the optional `C' and `N' prefixes indicate that each vertex
  981. includes colors and normals respectively.  That is, these files
  982. begin with one of the words
  983.  
  984. `QUAD' `CQUAD' `NQUAD' `CNQUAD' `POLY'
  985. `CPOLY' `NPOLY' `CNPOLY'
  986.  
  987. (but not `NCQUAD' or `NCPOLY').  `QUAD' and `POLY'
  988. are synonymous; both forms are allowed just for compatibility with
  989. ChapReyes.
  990.  
  991. Following the key word is an arbitrary number of groups of four
  992. vertices, each group describing a quadrilateral.  See the Vertex syntax
  993. above.  The object ends at end-of-file, or with a closebrace if
  994. incorporated into an object reference (see above).
  995.  
  996. A `QUAD BINARY' file format is accepted; *Note Binary format::.  The
  997. first word of binary data must be a 32-bit integer giving the number of
  998. quads in the object; following that is a series of 32-bit floats,
  999. arranged just as in the ASCII format.
  1000.  
  1001. 
  1002. File: geomview  Node: MESH, Prev: QUAD, Up: Object File Formats, Next: BBP and BEZ
  1003.  
  1004. `MESH': rectangularly-connected mesh
  1005. ------------------------------------
  1006.  
  1007. The conventional suffix for a `MESH' file is `.mesh'.
  1008.  
  1009. The file syntax is
  1010.  
  1011.      [C][N][Z][4][U][u][v]MESH    # Key word
  1012.      NU NV            # Mesh dimensions
  1013.                                   # NU*NV vertices, in format specified
  1014.                                   # by initial key word
  1015.      VERTEX(u=0,v=0)  VERTEX(1,0)  ... VERTEX(NU-1,0)
  1016.      VERTEX(0,1) ...    VERTEX(NU-1,1)
  1017.      ...
  1018.      VERTEX(0,NV-1) ... VERTEX(NU-1,NV-1)
  1019.  
  1020. The key word is  `[C][N][Z][4][U][u][v]MESH'.
  1021. The optional prefix characters mean:
  1022.  
  1023. `C'
  1024.      Each vertex (see Vertices above) includes a 4-component color.
  1025. `N'
  1026.      Each vertex includes a surface normal vector.
  1027. `Z'
  1028.      Of the 3 vertex position values, only the Z component is present; X and
  1029.      Y are omitted, and assumed to equal the mesh (u,v) coordinate so X
  1030.      ranges from 0 .. (Nu-1), Y from 0 .. (Nv-1) where Nu and Nv are the mesh
  1031.      dimensions -- see below.
  1032. `4'
  1033.      Vertices are 4D, each consists of 4 floating values.  `Z' and
  1034.      `4' cannot both be present.
  1035. `U'
  1036.      Each vertex includes a 3-component texture space parameter.  This is
  1037.      not yet implemented and should not be used.
  1038. `u'
  1039.      The mesh is wrapped in the u-direction, so the 
  1040.      (0,v)'th vertex is connected to the (NU-1,v)'th for all v.
  1041. `v'
  1042.      The mesh is wrapped in the v-direction, so the (u,0)'th vertex is
  1043.      connected to the (u,NV-1)'th for all u.  Thus a u-wrapped or
  1044.      v-wrapped mesh is topologically a cylinder, while a uv-wrapped mesh is a
  1045.      torus.
  1046.  
  1047. Note that the order of prefix characters is significant; a colored,
  1048. u-wrapped mesh is a `CuMESH' not a `uCMESH'.
  1049.  
  1050. Following the mesh header are integers NU and NV,
  1051. the dimensions of the mesh.
  1052.  
  1053. Then follow NU*NV vertices, each in the form given by the header.
  1054. They appear in v-major order, i.e. if we name each vertex by (u,v)
  1055. then the vertices appear in the order
  1056.  
  1057.      (0,0) (1,0) (2,0) (3,0) ...  (NU-1,0)
  1058.      (0,1) (1,1) (2,1) (3,1) ...  (NU-1,1)
  1059.      ...
  1060.      (0,Nv-1)        ...  (NU-1,NV-1)
  1061.  
  1062. A `MESH BINARY' format is accepted; *Note Binary format::.  The
  1063. values of NU and NV are 32-bit integers; all other values
  1064. are 32-bit floats.
  1065.  
  1066. 
  1067. File: geomview  Node: BBP and BEZ, Prev: MESH, Up: Object File Formats, Next: OFF
  1068.  
  1069. Bezier Surfaces
  1070. ---------------
  1071.  
  1072. The conventional file suffixes for Bezier surface files are `.bbp'
  1073. or `.bez'.  A file with either suffix may contain either type of
  1074. patch.
  1075.  
  1076. Syntax:
  1077.  
  1078.        [ST]BBP -or- [C]BEZ<NU><NV><ND>[_ST]
  1079.                  # NU, NV are u- and v-direction 
  1080.                  # polynomial degrees in range 1..6
  1081.                  # ND = dimension: 3->3-D, 4->4-D (rational)
  1082.                  # (The '<' and '>' do not appear in the input.)
  1083.                  # NU,NV,ND are each a single decimal digit.
  1084.                  # BBP form implies NU=NV=ND=3 so BBP = BEZ333.
  1085.  
  1086.              # Any number of patches follow the header
  1087.                  # (NU+1)*(NV+1) patch control points
  1088.                  # each 3 or 4 floats according to header
  1089.        VERTEX(u=0,v=0)  VERTEX(1,0) ... VERTEX(NU,0)
  1090.        VERTEX(0,1)               ... VERTEX(NU,1)
  1091.        ...
  1092.        VERTEX(0,NV)           ... VERTEX(NU,NV)
  1093.  
  1094.                  # ST texture coordinates if mentioned in header
  1095.        `S'(u=0,v=0)    `T'(0,0)    `S'(0,NV) `T'(0,NV)
  1096.        `S'(NU,0)    `T'(NU,0)    `S'(NU,NV) `T'(NU,NV)
  1097.  
  1098.                  # 4-component float (0..1) R G B A colors
  1099.                  # for each patch corner if mentioned in header
  1100.        `RGBA'(0,0)   `RGBA'(0,NV)
  1101.        `RGBA'(NU,0)  `RGBA'(NU,NV)
  1102.  
  1103. These formats represent collections of Bezier surface patches, of
  1104. degrees up to 6, and with 3-D or 4-D (rational) vertices.
  1105.  
  1106. The header keyword has the forms `[ST]BBP' or
  1107. `[C]BEZ<NU><NV><ND>[_ST]' (the '<' and '>' are
  1108. not part of the keyword.
  1109.  
  1110. The `ST' prefix on `BBP', or `_ST' suffix on
  1111. `BEZuvn', indicates that each patch includes four pairs of
  1112. floating-point texture-space coordinates, one for each corner of the
  1113. patch.
  1114.  
  1115. The `C' prefix on `BEZuvn' indicates a colored patch,
  1116. including four sets of four-component floating-point colors (red, green,
  1117. blue, and alpha) in the range 0..1, one color for each corner.
  1118.  
  1119. NU and NV, each a single digit in the range 1..6, are the
  1120. patch's polynomial degree in the u and v direction respectively. 
  1121.  
  1122. ND is the number of components in each patch vertex, and must be
  1123. either `3' for 3-D or `4' for homogeneous coordinates, that
  1124. is, rational patches.
  1125.  
  1126. `BBP' patches are bicubic patches with 3-D vertices, so `BBP'
  1127. = `BEZ333' and `STBBP' = `BEZ333_ST'.
  1128.  
  1129. Any number of patches follow the header.  Each patch comprises a series
  1130. of patch vertices, followed by optional (s,t) texture coordinates,
  1131. followed by optional (r,g,b,a) colors.
  1132.  
  1133. Each patch has (NU+1)*(NV+1) vertices in v-major order, so that if we
  1134. designate a vertex by its control point indices (u,v) the order is
  1135.           (0,0) (1,0) (2,0) ...  (NU,0)
  1136.           (0,1) (1,1) (2,1) ...  (NU,1)
  1137.           ...
  1138.           (0,NV)            ...  (NU,NV)
  1139. with each vertex containing either 3 or 4 floating-point numbers
  1140. as specified by the header.
  1141.    
  1142. If the header calls for ST coordinates, four pairs of floating-point
  1143. numbers follow: the texture-space coordinates for the (0,0),
  1144. (NU,0), (0,NV), and (NU,NV) corners of the
  1145. patch, respectively.
  1146.  
  1147. If the header calls for colors, four four-component (red, green, blue,
  1148. alpha) floating-point colors follow, one for each patch corner.
  1149.  
  1150. The series of patches ends at end-of-file, or with a closebrace if
  1151. incorporated in an object reference.
  1152.  
  1153. 
  1154. File: geomview  Node: OFF, Prev: BBP and BEZ, Up: Object File Formats, Next: VECT
  1155.  
  1156. OFF Files
  1157. ---------
  1158.  
  1159. The conventional suffix for `OFF' files is `.off'.
  1160.  
  1161. Syntax:
  1162.  
  1163.      [C][N][4]OFF        # Header keyword (optional)
  1164.      NVERTICES  NFACES  NEDGES   # NEdges not used or checked
  1165.  
  1166.      X[0]  Y[0]  Z[0]    # Vertices, possibly with colors
  1167.                      # and/or normals if `COFF' or `NOFF'
  1168.      ...
  1169.      X[NVERTICES-1]  Y[NVERTICES-1]  Z[NVERTICES-1]
  1170.  
  1171.                      # Faces
  1172.                      # NV = # vertices on this face
  1173.                      # V[0] ... V[NV-1]: vertex indices
  1174.                      #        in range 0..NVERTICES-1
  1175.      NV  V[0] V[1] ... V[NV-1]  COLORSPEC
  1176.      ...
  1177.                      # COLORSPEC continues past V[NV-1]
  1178.                      # to end-of-line; may be 0 to 4 numbers
  1179.                      # nothing: default
  1180.                      #  integer: colormap index
  1181.                      # 3 or 4 integers: RGB[A] values 0..255
  1182.                      # 3 or 4 floats: RGB[A] values 0..1
  1183.  
  1184. `OFF' files (name for "object file format") represent collections
  1185. of planar polygons with possibly shared vertices, a convenient way to
  1186. describe polyhedra.  The polygons may be concave but there's no
  1187. provision for polygons containing holes.
  1188.  
  1189. An `OFF' file may begin with the keyword `OFF'; it's
  1190.  
  1191.  
  1192.  
  1193. recommended but optional, as many existing files lack this keyword.
  1194.  
  1195. Three ASCII integers follow: NVERTICES, NFACES, and
  1196. NEDGES.  Thse are the number of vertices, faces, and edges,
  1197. respectively.  Current software does not use nor check NEDGES; it
  1198. needn't be correct but must be present.
  1199.  
  1200. The vertex coordinates follow: dimension * NVERTICES
  1201. floating-point values.  They're implicitly numbered 0 through
  1202. NVERTICES-1.  dimension is either 3 (default) or 4 (specified by
  1203. the key character `4' directly before `OFF' in the keyword).
  1204.  
  1205. Following these are the face descriptions, typically written
  1206. with one line per face.  Each has the form
  1207.      N  VERT1 VERT2 ... VERTN  [COLOR]
  1208. Here N is the number of vertices on this face,
  1209. and VERT1 through VERTN are indices into the list of
  1210. vertices (in the range 0..NVERTICES-1).
  1211.  
  1212. The optional COLOR may take several forms.  Line breaks are
  1213. significant here: the COLOR description begins after VERTN
  1214. and ends with the end of the line (or the next # comment).  A
  1215. COLOR may be:
  1216.  
  1217. nothing
  1218.      the default color
  1219. one integer
  1220.      index into "the" colormap; see below
  1221. three or four integers
  1222.      RGB and possibly alpha values in the range 0..255
  1223. three or four floating-point numbers
  1224.      RGB and possibly alpha values in the range 0..1
  1225.  
  1226. For the one-integer case, the colormap is currently read from the file
  1227. `cmap.fmap' in Geomview's `data' directory.  Some better
  1228. mechanism for supplying a colormap is likely someday.
  1229.  
  1230. The meaning of "default color" varies.  If no face of the object has a
  1231. color, all inherit the environment's default material color.  If some
  1232. but not all faces have colors, the default is gray (R,G,B,A=.666).
  1233.  
  1234. A `[C][N]OFF BINARY' format is accepted; *Note Binary format::.  It
  1235. resembles the ASCII format in almost the way you'd expect, with 32-bit
  1236. integers for all counters and vertex indices and 32-bit floats for
  1237. vertex positions (and vertex colors or normals if
  1238. `COFF'/`NOFF'/`CNOFF' format).
  1239.  
  1240. Exception: each face's vertex indices are followed by an integer
  1241. indicating how many color components accompany it.  Face color
  1242. components must be floats, not integer values.  Thus a colorless
  1243. triangular face might be represented as
  1244.  
  1245.      int int int int int
  1246.      3   17   5   9   0
  1247.  
  1248. while the same face colored red might be
  1249.  
  1250.      int int int int int float float float float
  1251.       3  17   5   9   4   1.0   0.0   0.0   1.0
  1252.  
  1253.  
  1254. 
  1255. File: geomview  Node: VECT, Prev: OFF, Up: Object File Formats, Next: INST
  1256.  
  1257. VECT Files
  1258. ----------
  1259.  
  1260. The conventional suffix for `VECT' files is `{.vect}.'
  1261. Syntax:
  1262.  
  1263.      [4]VECT
  1264.      NPOLYLINES  NVERTICES  NCOLORS
  1265.  
  1266.      NV[0] ... NV[NPOLYLINES-1]     # number of vertices
  1267.                                                 # in each polyline
  1268.  
  1269.      NC[0] ... NC[NPOLYLINES-1]     # number of colors supplied
  1270.                                                 # in each polyline
  1271.  
  1272.      VERT[0] ... VERT[NVERTICES-1]  # All the vertices
  1273.                                                 # (3*NVertices floats)
  1274.  
  1275.      COLOR[0] ... COLOR[NCOLORS-1]  # All the colors
  1276.                                                 # (4*NColors floats, RGBA)
  1277.  
  1278. `VECT' objects represent lists of polylines (strings of connected
  1279. line segments, possibly closed).  A degenerate polyline can be used to
  1280. represent a point.
  1281.  
  1282. A `VECT' file begins with the key word `VECT' or `4VECT'
  1283. and three integers: NLINES, NVERTICES, and NCOLORS.
  1284. Here NLINES is the number of polylines in the file,
  1285. NVERTICES the total number of vertices, and NCOLORS the
  1286. number of colors as explained below.
  1287.  
  1288. Next come NLINES integers
  1289.  
  1290.      NV[0] NV[1] NV[2] ... NV[NLINES-1]
  1291.  
  1292. giving the number of vertices in each polyline.  A negative number
  1293. indicates a closed polyline; 1 denotes a single-pixel point.  The sum
  1294. (of absolute values) of the NV[I] must equal NVERTICES.
  1295.  
  1296. Next come NLINES more integers Nc[i]: the number of colors in
  1297. each polyline.  Normally one of three values:
  1298.  
  1299. 0
  1300.      No color is specified for this polyline.  It's drawn in the same color
  1301.      as the previous polyline.
  1302. 1
  1303.      A single color is specified.  The entire polyline is drawn in that
  1304.      color.
  1305. abs(NV[I])
  1306.      Each vertex has a color.  Either each segment is drawn in the
  1307.      corresponding color, or the colors are smoothly interpolated along the
  1308.      line segments, depending on the implementation.
  1309.  
  1310. The sum of the NC[I] must equal NCOLORS.
  1311.  
  1312. Next come NVERTICES groups of 3 or 4 floating-point numbers: the
  1313. coordinates of all the vertices.  If the keyword is 4VECT then
  1314. there are 4 values per vertex.  The first abs(NV[0]) of them form
  1315. the first polyline, the next abs(NV[1]) form the second and so on.
  1316.  
  1317. Finally NCOLORS groups of 4 floating-point numbers give red,
  1318. green, blue and alpha (opacity) values.  The first NC[0] of them
  1319. apply to the first polyline, and so on.
  1320.  
  1321. A VECT BINARY format is accepted; *Note Binary format::.  The
  1322. binary format exactly follows the ASCII format, with 32-bit ints where
  1323. integers appear, and 32-bit floats where real values appear.
  1324.  
  1325.  
  1326.  
  1327. 
  1328. File: geomview  Node: INST, Prev: VECT, Up: Object File Formats, Next: INST Examples
  1329.  
  1330. INST Files
  1331. ----------
  1332.  
  1333. The conventional suffix for a `INST' file is `.inst'.
  1334.  
  1335. An `INST' applies a 4x4 transformation to another OOGL object.  It
  1336. begins with `INST' followed by these sections which may appear in
  1337. any order:
  1338.      geom OOGL-OBJECT
  1339. specifies the OOGL object to be instantiated.  *Note References::, for
  1340. the syntax of an OOGL-OBJECT.  The keyword `unit' is a
  1341. synonym for `geom'.
  1342.      transform   ["{"] `4x4 transform' ["}"]
  1343. specifies a single transformation matrix.  Either the
  1344. matrix may appear literally as 16 numbers, or there may be
  1345. a reference to a "transform" object, i.e.
  1346.      "<" file-containing-4x4-matrix
  1347. or
  1348.      ":" symbol-representing-"transform"-object>
  1349.  
  1350. Another way to specify the transformation is
  1351.  
  1352.      transforms
  1353.          OOGL-OBJECT
  1354.  
  1355. The OOGL-OBJECT must be a `TLIST' object (list of
  1356. transformations) object, or a `LIST' whose members are ultimately
  1357. `TLIST' objects.  In effect, the `transforms' keyword takes a
  1358. collection of 4x4 matrices and replicates the `geom' object, making
  1359. one copy for each 4x4 matrix.
  1360.  
  1361. If no `transform' nor `transforms' keyword appears, no
  1362. transformation is applied (actually the identity is applied).  This
  1363. might be useful, e.g., for wrapping an appearance around an
  1364. externally-supplied object.
  1365.  
  1366. *Note Transformation matrices::, for the matrix format.
  1367.  
  1368. There is no INST BINARY format.
  1369.  
  1370. * Menu:
  1371.  
  1372. * INST Examples::    Some example of `INST' Files.
  1373.  
  1374. 
  1375. File: geomview  Node: INST Examples, Prev: INST, Up: Object File Formats, Next: LIST
  1376.  
  1377. INST Examples
  1378. .............
  1379.  
  1380. Here are some examples of `INST' files
  1381.  
  1382.      INST
  1383.           unit < xyz.vect
  1384.           transform {
  1385.              1 0 0 0
  1386.              0 1 0 0
  1387.              0 0 1 0
  1388.              1 3 0 1
  1389.           }
  1390.  
  1391.      { appearance { +edge  material { edgecolor 1 1 0 } }
  1392.          INST geom < mysurface.quad }
  1393.  
  1394.      {INST transform {: T} geom {<dodec.off}}
  1395.  
  1396.      { INST
  1397.           transforms
  1398.               { LIST
  1399.               { < some-matrices.prj }
  1400.               { < others.prj }
  1401.               { TLIST <still more of them> }
  1402.          
  1403.               }
  1404.           geom
  1405.               { # stuff replicated by all the above matrices
  1406.               ...
  1407.               }
  1408.      }
  1409.  
  1410. 
  1411. File: geomview  Node: LIST, Prev: INST Examples, Up: Object File Formats, Next: TLIST
  1412.  
  1413. LIST Files
  1414. ----------
  1415.  
  1416. The conventional suffix for a `LIST' file is `.list'.
  1417.  
  1418. A list of OOGL objects
  1419.  
  1420. Syntax:
  1421.  
  1422.      LIST
  1423.          OOGL-OBJECT
  1424.          OOGL-OBJECT
  1425.          ...
  1426.  
  1427. Note that there's no explicit separation between the oogl-objects, so
  1428. they should be enclosed in curly braces ({ }) for sanity.  Likewise
  1429. there's no explicit marker for the end of the list; unless appearing
  1430. alone in a disk file, the whole construct should also be wrapped in
  1431. braces, as in:
  1432.  
  1433.         { LIST { QUAD ... } { < xyz.quad } }
  1434.  
  1435. A `LIST' with no elements, i.e. `{ LIST }', is valid, and is
  1436. the easiest way to create an empty object.  For example, to remove a
  1437. symbol's definition you might write
  1438.  
  1439.         { define somesymbol  { LIST } }
  1440.  
  1441.  
  1442. 
  1443. File: geomview  Node: TLIST, Prev: LIST, Up: Object File Formats, Next: GROUP
  1444.  
  1445. TLIST Files
  1446. -----------
  1447.  
  1448.  
  1449. The conventional suffix for a `TLIST' file is `.grp' ("group")
  1450. or or `.prj' ("projective" matrices).
  1451.  
  1452. Collection of 4x4 matrices, used in the `transforms' section of and
  1453. `INST' object.
  1454.  
  1455. Syntax:
  1456.  
  1457.      TLIST            # key word
  1458.  
  1459.      <4x4 matrix (16 floats)>
  1460.      ...                # Any number of 4x4 matrices
  1461.  
  1462. `TLIST's are used only within the `transforms' clause of an
  1463. `INST' object.  They cause the `INST's `geom' object to
  1464. be instantiated once under each of the transforms in the `TLIST'.
  1465. The effect is like that of a `LIST' of `INST's each with a
  1466. single transform, and all referring to the same object, but is more
  1467. efficient.
  1468.  
  1469. Be aware that a `TLIST' is a kind of geometry object, distinct from a 
  1470. `transform' object.  Some contexts expect one type of object,
  1471. some the other.  For example in
  1472.      INST transform { : MYT } geom { ... }
  1473. MYT must be a transform object, which might have been
  1474. created with the gcl
  1475.      (read transform { define myT 1 0 0 1 ... })
  1476. while in
  1477.          INST transforms { : MYTS } geom { ... }
  1478.      or  INST transforms { LIST {: MYTS} {< more.prj} } geom { ... }
  1479. MYTS must be a geometry object, defined e.g. with
  1480.          (read geometry { define MYTS { TLIST 1 0 0 1 ... } })
  1481.  
  1482. A `TLIST BINARY' format is accepted.  Binary data begins with a
  1483. 32-bit integer giving the number of transformations, followed by that
  1484. number of 4x4 matrices in 32-bit floating-point format.  The order of
  1485. matrix elements is the same as in the ASCII format.
  1486.  
  1487.  
  1488. 
  1489.